BBS in a Box 7/BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso/Files/Tele/Pete Johnson/mehit 2.06.cpt/mehit 2.06/mehit Complete Help Text

Text File | 1990-05-24 | 29KB | 667 lines

The following is a complete text transcript of the mehitabel help file.
It is organized in alphabetical order, by topic. This file was created
to make it easy for you to browse mehitabel’s help files when you don’t
have access to a computer.

                            About mehit…

mehitabel is a utility designed to automate backup of message sections,
with optional size control of message sections based on limits and ages
of messages in each section.

Limits: mehitabel gives you the ability to set limits for each section.
A message section which has more messages than its limit will be
trimmed, with the oldest messages in the section deleted until the
section meets its limit. If you enter a limit of 0 (zero) for a section,
mehitabel leaves it alone. If you enter a limit of -1 for a section,
mehitabel deletes all messages in that section (useful for cleaning out
“Unknown” sections and the results of accidents).

Age: mehitabel will delete any message older than the number of days you
specify for each section. An entry of 0 (zero) tells mehitabel to leave
the section alone.

In normal use, mehitabel backs up the MESSAGES, MSGHDR and MSGTXT files
to a location of your choosing, scanning the MSGHDR file to count
messages in each section during the backup. A second pass through the
three files purges them of deletes and messages which don’t meet Limits
and Age criteria. At the end of processing, mehitabel leaves you with
unaltered copies of your original files — MESSAGES.Bak, MSGHDR.Bak and
MSGTXT.Bak — and a set of three ready-to-go cleaned message files.

mehitabel works with Red Ryder Host, with or without Tabby. For notes on
setup with and without Tabby, read the Setup section of this help file.

                            Alter Section

This dialog window allows you to set options for each individual message
section.

For maximum convenience, all buttons in this window respond to
Command-key equivalents: Command-P takes you to the Previous entry,
Command-B toggles the backup setting, Command-C Cancels and so forth.

Limit sets the maximum number of messages allowed in the currently
selected section.

Age sets the maximum number of days a message is considered valid.

Backup determines whether or not deleted messages are archived to a text
file.

Save records the changes for the currently selected section and exits.

Cancel ignores the changes for the currently selected section and exits.

All four movement buttons — Previous, Next, First and Last —
automatically save the settings for the  currently selected section.

Help summons this Help window.

                            Backup Options

mehitabel offers three backup options:

Normal Backup: This makes copies of the current MESSAGES, MSGHDR and
MSGTXT files and saves them as MESSAGES.Bak, MSGHDR.Bak and MSGTXT.Bak
in the volume and/or folder you designate in the Configure dialog. These
are exact copies of the three files as they were when mehitabel started.
This option is the safest, and is mehit’s “normal” mode of operation.

Kill Backups When Done: This option makes the backups before mehitabel
processes the three files, but kills the three backup files when all is
done. This leaves you a bit more working space on your hard disk when
mehitabel is not running, though you lose the protection of an
ever-fresh backup copy of your messages.

Purge Without Backup: In this mode, mehitabel makes no backups, but does
an in-place purge of the message files. Use this if you are short on
disk space, but be warned: This mode of operation will destroy your
messages if there is a power failure, system crash or other interruption
during the backup process!

                            Configure

This dialog lets you design the behavior of mehitabel.

next launch is the application which mehitabel should jump to when it’s
done, in the absence of other instructions (such as Tabby’s Launch.Next
file, which overrides this item). If you are not running TabbyNet and
want to have Host launch mehitabel as a pseudo NetMail event, just put
Red Ryder Host (or whatever you call Host) in this field, and mehitabel
will return control to Host when it’s done. If you want to run an
application other than Host after mehit, you can enter its name instead.

backup path is the location where mehitabel should create backup files
of your message sections if you select normal backup or kill backups
when done. This option allows you to use a volume other than your
primary volume for backups — useful if you’re running low on space in
your primary volume. If you choose purge without backup, this
information is not used.

text files path sets the location where mehitabel will store text files
such as its reports (if you activate them) and/or text backups of
messages.

b/u text path is the location where mehitabel will store text files
resulting from the b/u option for message sections.

The Select buttons to the right of these first four options allow you to
use a standard Macintosh file dialog to select the information.

The four lefthand check boxes let you choose whether or not mehit writes
to the Tabby Log, whether mehit creates a full report, whether mehit
creates a brief report and whether mehit maintains a message error log.
Samples of the full and brief reports can be found within this Help
dialog.

max b/u text size lets you set a size limit (in kilobytes) for text
files resulting from the b/u option. mehit trims these files from the
top until they meet your criterion. This value applies to all b/u text
files. If you don’t want them trimmed, enter a zero for this value.

The three righthand radio buttons let you select mehit’s backup style:

normal backup means that at the beginning of its session, mehit reads
the MESSAGES, MSGHDR and MSGTXT files and writes copies of them in the
Backup Path location as MESSAGES.Bak, MSGHDR.Bak and MSGTXT.Bak.

kill backups when done is identical to Normal Backup — mehit makes
copies of the three message component files at the beginning of the
session — but mehitabel kills the copies when the session is completed.
This option, which is clearly less secure than Normal Backup, is offered
for those who are tight on disk space and want the extra room this
option leaves.

purge without backup is dangerous. No backups are made. Instead, mehit
does an in-place purge of the message files, deleting and erasing excess
messages. If mehitabel is not interrupted by an event such as a power
failure or a disk crash, this should work fine, but it leaves you with
no backup, and if mehitabel is  interrupted, you’re guaranteed a trashed
message base. This option is offered for those who are really  hard up
for disk space, and who dare to risk their messages as a consequence.

Help summons this dialog.

Cancel ignores the changes you’ve made.

OK saves your changes in mehit’s resources.

                            Credits

• This styled text help system was written by R. Fronabarger, who
deserves a big thank you. Thanks also to Andrew Welch, who wrote a
helpful procedure for centering windows.

• The name mehitabel  is inspired by the works of Don Marquis, a
wonderful writer who invented the first mehitabel and the first Archie
and who wrote about them in his newspaper columns. If you find any of
his books, read them — they’re both funny and wise.

• Thanks also to Bruce Gerson and Ed Edell, who suggested good
suggestions and bravely beta tested the results. And to Ray Terry, who
discovered and identified a subtle but significant bug.

• mehitabel was written by Pete Johnson in LightSpeed Pascal. The
program is ©1989 by Pete Johnson.

                            Cursors

mehitabel’s round cursor was developed after wind tunnel tests revealed
that the conventional Macintosh arrow cursor suffers from excessive drag
coefficients at high mouse velocities. The original “hot spot” was the
tip of mehit’s nose, but beta testers complained that they couldn’t find
it. The current hot spot is in mehit’s eye. Not that it matters, since
the mehit cursor now yields to the arrow cursor whenever there's work to
be done.

The flipping dogcow cursor which appears when you save mehit resources
is borrowed from Apple’s Tech Notes Stack from Developer Services, which
has made a cult item out of the dogcow. If you want to know more about
the dogcow, find a copy of the elusive Apple Technical Note 31.

                            Customizing

If you want to modify mehitabel in ways that the Configure dialog
doesn’t offer and are handy with ResEdit, here are some STR s you can
change:

STR 510 holds the name of the mehit big report. If you want to name it
differently, enter the name here.

STR 511 holds the name of the mehit brief report. If you want to name it
differently, enter the name here.

STR 512 holds the name of the message error log. If you want to name it
differently, enter the name here.

STR 513 holds the name of the message orphans report. If you want to
name it differently, enter the name here.

STR  514, which is empty when mehitabel is shipped, can be used to hold
a string to separate messages in text archives. With nothing entered in
STR  514, mehitabel just writes an extra line with two nulls (ASCII
zeroes) between messages. If, for instance, you want a line of hyphens
to separate messages, enter the hyphens in STR  514.

                            Demo

If you are running the demo version of mehitabel, please be aware that
it will forget its limits, age and backup settings twice a month (on the
1st and 16th) and will require reconfiguration. It always remembers the
basic configuration info — where you want to put your text files and so
on — but twice a month it will forget the processing specifics for each
section.

No harm is done by this amnesia. mehit will still back up and repair
everything as always, but it won’t selectively trim messages until you
reconfigure it.

(If you aren’t sure whether you have the Demo version, run mehitabel
while holding down the mouse button. When everything settles down,
choose “about mehitabel” from the Apple menu. The demo version is
identified in the version information in the lower lefthand corner of
the “about…” window. The word “demo” also appears in mehitabel’s
processing window for the demo version.)

Since the demo version of mehitabel is programmed for amnesia during the
full 24-hour period of the 1st and 16th of each month, don’t bother to
reconfigure it and run it on those days — it will just forget its
settings again. Wait a day, then refresh its memory for the next couple
of weeks.

If you want to get a copy of the registered users version, which does
not suffer from this inconvenience, please read the Registration
information section. If you are already an Archie and mehitabel
registered user, send a blank disk and a self addressed stamped envelope
(preferably padded) to:

Pete Johnson
Post Office Box 65074
Los Angeles, CA 90065

and I’ll fill the disk with the latest versions of my utilities,
including the “total recall” version of mehitabel, and send it back to
you.

                            Global Commands

The Global commands available from the main Sections window allow you to
set parameters — Limit, Age and Backup to Text — for all message
sections simultaneously. This is a great timesaver when you first
configure mehitabel, since many settings are apt to be the same. You can
subsequently  double-click individual sections to alter their
parameters.

                            Hints & Tips

• Host 2.0x performs best with 2,000 or fewer total messages. More
messages slow Host down greatly.

• For additional speed, don’t let your UserLog grow out of control. A
big UserLog slows down users when they log in (Host has to find the
user’s name), slows down new message saves (Host searches the UserLog
every time it saves a message — if the addressee is a bona fide user,
Host sets his or her “mail waiting” flag) and also slows down Tabby
message import programs.

• Use Tally’s* 10-day report to help you set message limits. This report
shows you traffic during the last 10 days in each message section. Use
this information to regulate low- and high-volume message sections.
(Example: if you want to make sure that a caller who only checks in
every four days never misses a message in the Writing Echo, scan the
10-day report for that Echo and set the limit to a figure that will
handle the highest four-day total).

• To make sure that mehit never deletes NetMail you haven’t seen (for
instance: when a system that feeds you messages has been down for a few
days, it may deliver a packet which exceeds the limits you’ve set for
some Echoes), run mehit at the beginning of your regular NetMail event,
before any mail has been delivered. This gives you a 24-hour window in
which to read everything.

* Tally is part of the Archie Registered Users package. To learn more,
please read the Registration information section.

                            How mehit Works

Here is a step-by-step explanation of how mehitabel works. This may be
useful if you’re trying to recover from a disaster and want to know what
mehitabel was doing at a certain point.

When mehitabel first starts up, it reads the Config file to find out
where the MESSAGES file can be found. It then opens the MESSAGES file to
find out where MSGHDR and MSGTXT are.

At this point, if you are holding down the mouse button, mehitabel
branches to its “configuration” mode. Otherwise…

mehitabel draws an “in progress” dialog on the screen, starts its timer
going and reads its STR  resources. If you’ve told it to write to the
Tabby Log, it writes a “program starting” entry.

If you’ve specified Normal or Kill After backup options, mehit proceeds
to copy MESSAGES, MSGHDR and MSGTXT, writing the results as
MESSAGES.Bak, MSGHDR.Bak (analyzing MSGHDR as it copies) and MSGTXT.Bak
wherever you’ve designated. If you haven’t asked mehitabel to back up
anything, then mehit just analyzes the MSGHDR file, getting a count of
active and deleted messages in each section.

Now comes the work part: mehitabel checks the message section counts
against its configuration, and notes whether any sections are over their
limits. In the following steps, mehit uses a single 125-entry buffer for
the MSGHDR file and a 50K buffer for the MSGTXT file. It fills the
respective buffers from the source files, marks messages for deletion as
necessary, purges deleted messages and relocates the survivors in a
continuous sequence. (If you’ve asked mehit to archive deleted messages,
this is done now, too.) When the buffers are processed, they’re written
out to the files and refilled, until the file has been completely
processed. This “in place” backup method minimizes space requirements on
your disk and allows flexible backup options.

When this is finished, mehitabel adjusts the MESSAGES file to reflect
new low and high message numbers, along with the new figure for the
length of the MSGTXT file.

If you’ve asked mehit to kill the backups after processing, that happens
next.

If mehit has been asked to trim text files within a maximum length, this
happens now.

If you’ve selected the Big Report option, mehitabel now writes a Big
Report. Brief Report comes next.

If you’ve asked mehit to write to the Tabby Log, mehit now writes a
“program ending” entry.

Finally, mehit checks out its status in the Tabby chain, dumps its
in-progress dialog and either launches the next Tabby application or
quits to the Desktop, depending on the contents (or lack of contents) of
the launch.next file.

                            Memory Considerations

To increase its speed, mehitabel uses buffers for all file transfers.
Though none of the buffers is huge, they do require memory.

mehitabel has been tested on BBSs using Mac Pluses with 1 meg of RAM and
on a 512K Mac which was also running TOPS. From the results of these
tests, I think it’s unlikely to run out of memory.

Typically, mehitabel would like to have about 140K for basic file
buffers, and another 60K if you’re archiving deleted messages to text.
mehitabel checks to make sure there is enough memory to open all the
file buffers, tries to adjust its needs to what’s available and warns
you if it can’t. If you’re not archiving deleted messages to text,
mehitabel can make do with as little as 75K in buffers (though it will
run a bit slower).

If you get a “need more memory” warning, here’s what you can do:

• Eliminate or reduce the size of your Control Panel RAM Cache, if
you’re using one.

• Eliminate or reduce the size of any RAM Disks.

• Trim down your INITs — some INITs are major memory hogs.

• Don’t use mehit to archive deleted files to text — this will save you
about 60K.

                            Menus

The following is a summary of mehitabel menu functions:

file

configure… takes you to the Configuration dialog, where you set paths
for text files and tell mehit how to behave.

run mehitabel closes the window, runs mehitabel and launches the next
event, using information in the Tabby launch.next file or the default
set for mehitabel through the Configuration dialog. If no next event is
found, mehit quits when finished.

save changes stores the current settings.

revert lets you discard current changes and return to the settings last
saved for mehitabel.

save msg list as text… saves a text copy of the message sections listed,
with their section numbers and limits. You will be prompted to name this
text file.

transfer… lets you jump straight to another program.

quit exits mehitabel.

edit

The edit menu supports the standard Macintosh editing functions: Undo,
Cut, Copy, Paste and Clear. These are not operative in mehitabel, but
are provided for use by Desk Accessories.

global

set global limits… lets you set message count limits for all message
sections simultaneously.

set global age… lets you set the maximum age of active messages for all
message sections simultaneously.

set global backup status… lets you set the “archive deleted messages to
text” status of all message sections simultaneously.

help summons this help system.

                            Message Errors

mehitabel automatically deletes any messages with obvious file structure
problems. This feature has salvaged a number of otherwise-unusable Red
Ryder Host message bases.

If the configuration option log message errors is enabled, mehitabel
will record any message errors in a text file called “message error
log”.

Each entry in the message error log is identified by date, by error
category, by message number and by section number. Entries are appended
to the log, so it is an ongoing account of message problems. Messages
with these sorts of errors are deleted by mehitabel — if you want to see
what they looked like, check the backup files.

Message errors are identified in three common categories:

Number Error. These  messages are out of numerical sequence. Since
mehitabel reads messages from beginning to end, if a message does not
have the highest number so far recorded, has a number lower than the
lowest recorded message number or a number identical to the previous
message number, it qualifies for this error category.

Location Error. This is a message whose header points to a location
beyond the end of the MSGTXT file. I suspect that this is a common error
category.

Text Length Error. This is a message whose header indicates that it is
bigger than 30K (this is bigger than the theoretical limits of the
message specification) or less than zero in size.

                            MultiFinder

Mehitabel is not unfriendly towards MultiFinder, but neither is she
particularly friendly or aware. With the next release, I intend to
tackle the Mysteries of MultiFinder.

                            Orphans

Orphans are messages in undefined sections. They can result from
maintenance sessions in which you eliminate and redefine your message
sections, forgetting that some messages may still exist in an eliminated
area.

mehitabel checks for orphans and writes the total found in the mehit big
report. If mehitabel finds orphans, she also creates a text file, called
message orphans, which lists the section numbers containing these
wayward messages. You can legitimize them by using MsgEdit, TMM or a
similar utility to create a valid message section. If you want to delete
them, create a valid message section for them, then set mehitabel’s
limit to -1 for this section. After you run mehitabel, you can undefine
the section.

                            Registration

mehitabel is part of the Archie registered users package. To get the
complete package, which includes many other fine Host and Tabby
utilities, send $25 to:

Pete Johnson
P.O. Box 65074
Los Angeles, CA 90065

If you are already an Archie and mehitabel registered user, send a blank
disk and a self addressed stamped envelope (preferably padded) to me and
I’ll fill it up with the latest versions of all my utilities and send it
back to you.

                            Report Formats

The brief report format is suitable for use as a text file which callers
can read. It contains a summary of BBS message section counts and a
total for all sections.

The long report format contains a complete report of mehitabel’s
activity, including numbers of deletes in all sections, active messages
in each section, time of run, total space used and many other
sysop-oriented nuggets of information.

                            Setup

To install mehitabel, do the following:

• Put mehitabel and the mehitabel help file in a working Host system, at
the same level as the Config file. You will need mehitabel help when you
are setting up. Later, you can remove it to save space and clutter, as
long as you don’t expect to ask mehitabel any questions.

• Launch mehitabel while holding down the mouse button. This will bring
you to a set of dialogs which allow you to configure mehitabel.

• Choose “Configure” from the File menu, and tell mehitabel what program
to launch next and where to put backups and text files. This dialog also
lets you choose which reports mehitabel will generate.

• Set Limits, Ages and Backup status for each section. If you do not
know what limits to set, leave them all at 0, set mehitabel to generate
a full report and run mehitabel once. With all sections set to 0,
mehitabel will not delete any messages. The mehitabel report will tell
you how many messages each section contains, enabling you to
intelligently decide what limits to set.

• If you are running Tabby, insert mehitabel in a regular Tabby event
(see the Hints help section for some advice on when to run mehitabel).

• If you are not running Tabby, then set Host to launch mehitabel as a
NetMail event at whatever time you choose, and set mehitabel’s “Next
Launch” option to the name of your Host application.

                            Shortcuts

• Every button in the Alter Section dialog responds to its Command-key
equivalent. For instance, you can select Previous by hitting Command-P,
or alter Backup status by hitting Command-B.

• Use the Global commands from the main Sections window to set Limit,
Age and Backup to Text parameters for all sections simultaneously, then
customize individual sections by double clicking them.


                            Speed

In normal operation, mehitabel 2.0 is about 24 times faster than
mehitabel 1.2 (really!). If speed is your goal, here are some things to
know:

• b/u to text slows mehitabel down. If you don’t really need it, you’ll
get better performance by not using it.

• RAM caching speeds mehitabel (and Tabby, and Host) up. You don’t need
a huge cache — 128K or 256K helps considerably.

                            Status Report

As mehitabel runs, a small status window indicates what is happening. In
addition to a mehitabel icon, the window contains a status line, a
progress indicator, a text box showing the program version number and
another text box which shows details of the session. mehitabel’s
activities fall into several categories, as indicated by the status
line:

Backing Up…
If you have configured mehitabel to make backups, she makes exact copies
of the three Host message files — MESSAGES, MSGHDR and MSGTXT — in the
folder you have designated. The lower right hand corner of the status
window shows which file is currently being copied. The progress
indicator shows approximately how much has been done and how much
remains to be done.

Cleaning…
This message appears when mehitabel is checking limits and age, purging
deleted messages and copying the deletes to text files (depending on her
configuration). The progress indicator fills in as mehit processes
messages, and the lower right hand text box is updated every 10th
message with the number of the message now being processed.

Trimming…
This message appears when mehitabel is checking the sizes of and
trimming text files resulting from archiving deleted messages.

Writing Reports…
This message shows that mehitabel is writing any reports you’ve
requested.

                            Text Archives

If you select b/u (or Backup) as an option for one or more message
sections, mehitabel will append all deleted messages in these sections
to text files called SectionName.txt, where SectionName is the actual
name of the message section from which the messages were archived. These
text files will be located in the folder you designate (b/u text path)
in the Configure dialog.

You can control the maximum size of these text archives by setting max
b/u text size in kilobytes in the Configure dialog. The number you enter
is multiplied by 1024 to produce a kilobyte result. If max b/u text size
is set at a number less than one, mehitabel does not regulate the file
size.

To control file size, mehitabel subtracts the limit you set from the
actual file size and begins reading the text, looking for the beginning
of the next message. Once the beginning is found, mehitabel rewrites the
file with the first message at the beginning. The result is a text file
which will almost always be a bit smaller than the limit you set, but
which has a clean beginning and ending.

mehitabel uses two nulls — ASCII zeroes — and an extra carriage return
to mark the end of each message. These nulls are invisible to almost all
programs.

If you want to put additional separation characters (hyphens, asterisks,
slashes or whatever) between messages, you can use ResEdit to modify STR
514. These characters will be appended to the line after the two nulls.
As shipped, STR  514 is empty.

Archiving to text is a useful technique to preserve messages without
clogging your main message sections. You can set up Archie to do text
file searches on these menus if you or your callers want to check for
messages which have scrolled off of the main sections.

                            In Case of Trouble

If mehitabel is interrupted or (heaven forbid) crashes during its
operation, you should be able to recover your messages rather easily:

1 — Rename the MESSAGES, MSGHDR and MSGTXT files to temporary names
(such as MESSAGES.temp, MSGHDR.temp and MSGTXT.temp).

2 — Rename the MESSAGES.Bak, MSGHDR.Bak and MSGTXT.Bak files to
MESSAGES, MSGHDR and MSGTXT and put them in the correct folders.

3 — Run Host to verify that all is well.

If everything works, you can toss the three .Temp files. If not, then
your message files suffered some calamity before mehitabel got to them.
Try running mehitabel on these three files again — mehit filters out
most kinds of “bad” message headers, and this filtering can often
recover trashed message files.

                            Who’s mehitabel?

there is always
a comforting thought
in time of trouble when
it is not our trouble
  —archy

oh i should worry and fret
death and i will coquette
there s a dance in the old dame yet
toujours gai toujours gai
  —mehitabel

Don Marquis (1878-1937), a newspaper columnist, created archy, a
cockroach who wrote verse and philosophy by diving from the top of a
manual typewriter headfirst onto its keys. archy wrote about himself and
some of the characters who prowled around Marquis’ desk after hours, one
of whom was a merry cat named mehitabel. Their names are spelled all
lowercase because archy did all the typing, and he couldn’t manage the
shift key with his headfirst technique (he also couldn’t manage
apostrophes or other shifted punctuation marks).

archy was not a primary inspiration for the name of Archie, a Host
Command 50 application which I wrote, but Marquis’ mehitabel is the
source of this one, including the icon, which I digitized from a sketch
in an Archy book. John Alcock says it looks like a ferret because of its
long nose, but that’s the way the person who illustrated mehitabel drew
cats.